Designing RESTful API Endpoints

Course: Advanced Java Training

Topic: Designing RESTful API Endpoints Using Java and Spring Boot

Course Link: Advanced Java Training Course

Demo Link: Register for a Free Course Demo

JustAcademy Website: Visit JustAcademy

1. Introduction to RESTful API Endpoints

A RESTful API is an application programming interface designed around REST (Representational State Transfer) principles. It allows different applications to communicate over HTTP by exchanging data and performing operations on resources.

For example, an e-commerce application may provide APIs to retrieve products, create orders, update customer information, and delete shopping cart items. A frontend application, mobile app, or external service can use these endpoints to interact with the backend.

In Java applications, Spring Boot simplifies REST API development through annotations such as @RestController, @GetMapping, @PostMapping, @PutMapping, @PatchMapping, and @DeleteMapping.

What Is an Endpoint?

An endpoint is a particular URL or URI through which a client accesses a resource or invokes an operation supported by an API. An endpoint typically works with an HTTP method to define the intended action.

For example:

GET /api/products
GET /api/products/101
POST /api/products
PUT /api/products/101
DELETE /api/products/101

These examples represent operations on a product collection and an individual product. The HTTP method determines the intended operation, while the URL identifies the target resource.

2. Learning Objectives

• Understand REST architecture and resource-oriented API design.
• Design meaningful and consistent endpoint URLs.
• Use HTTP methods correctly for CRUD operations.
• Apply HTTP status codes and response headers appropriately.
• Implement REST endpoints using Spring Boot.
• Handle path variables, query parameters, and JSON request bodies.
• Validate input and return structured error responses.
• Apply pagination, filtering, sorting, versioning, and security practices.
• Test endpoints using Postman, curl, and automated tests.

3. Understanding REST Principles

REST is an architectural style for distributed systems. A well-designed REST API follows several important principles.

3.1 Client-Server Architecture

The client and server have separate responsibilities. The client presents information and collects user input, while the server manages business logic, data access, and resource operations.

For example, a React frontend may request product information from a Spring Boot backend without needing to know how the backend stores its data.

3.2 Stateless Communication

Each request should contain the information required for the server to process it. The server should not depend on conversational session state retained from a previous request to understand the current request.

Authentication tokens, resource identifiers, and request parameters can be supplied as appropriate. Statelessness does not mean the application cannot store persistent business data; it means that request processing should not rely on hidden client-session context.

3.3 Resource-Based Design

REST APIs expose resources such as users, products, orders, employees, and payments. Resource names are generally nouns rather than action-oriented verbs.

Prefer:

GET /api/employees
POST /api/employees
DELETE /api/employees/25

Avoid designing every operation as a custom action URL, such as /api/getEmployees or /api/deleteEmployee/25, when standard resource operations are sufficient.

3.4 Consistent Interface

Endpoints should follow consistent naming conventions, HTTP method semantics, response formats, and error-handling rules. Consistency makes APIs easier to learn, document, test, and maintain.

3.5 Cacheability

Responses should indicate whether they can be cached when caching is appropriate. Correct cache headers can improve performance for frequently requested resources. Sensitive or frequently changing data may require restrictive caching policies.

4. Identifying Resources and Designing URLs

The first step in endpoint design is to identify the resources that the application manages. For an employee management system, resources might include employees, departments, and projects.

4.1 Use Nouns in Endpoint Paths

Use resource names to identify the target entity.

4.2 Use Plural Resource Names Consistently

Plural nouns are a common convention for collection endpoints. For example, use /api/customers for a collection and /api/customers/42 for one customer. Consistency matters more than any single naming convention.

4.3 Represent Relationships Clearly

Nested paths can express relationships when they are meaningful and easy to understand.

GET /api/departments/4/employees
GET /api/employees/25/projects
GET /api/orders/500/items

Nested paths are useful when the child resource is being accessed in the context of its parent. Avoid excessively deep nesting. If a resource has an independent identity, a direct endpoint may be clearer.

4.4 Use Path Variables for Resource Identity

A path variable identifies a specific resource or a meaningful part of its hierarchy.

GET /api/employees/25

In Spring Boot, the employee identifier can be extracted with @PathVariable.

@GetMapping("/api/employees/{id}")
public Employee getEmployee(@PathVariable Long id) {
    return employeeService.findById(id);
}

This example illustrates endpoint mapping. In a production application, the service should handle missing records, and the controller should return a suitable response when the employee does not exist.

5. Choosing the Correct HTTP Method

HTTP methods communicate the intended operation. Select the method according to the operation's semantics rather than its implementation details.

5.1 GET Requests

Use GET to retrieve information. A GET request should not cause a business-state change such as placing an order or deleting a record.

GET /api/products
GET /api/products/10

5.2 POST Requests

Use POST when submitting a representation to a collection to create a resource or when invoking an operation whose semantics are not covered by a more suitable method.

POST /api/products
Content-Type: application/json

{
  "name": "Wireless Mouse",
  "price": 799.00,
  "category": "Accessories"
}

When a new resource is created, a typical response is 201 Created, often with a Location header identifying the created resource.

5.3 PUT Versus PATCH

PUT normally replaces the target resource's representation, whereas PATCH applies a partial modification. A PUT implementation should define clearly which fields are required and how omitted fields are handled. PATCH must specify how partial updates are represented and interpreted.

PUT is defined as idempotent: repeating the same request should have the same intended effect as performing it once. PATCH is not automatically idempotent; its behavior depends on the patch operation.

5.4 DELETE Requests

Use DELETE to request removal of a resource.

DELETE /api/products/10

A successful DELETE may return 204 No Content if there is no response body, or another appropriate success status if the API returns a representation or operation result.

6. CRUD Endpoint Design

CRUD stands for Create, Read, Update, and Delete. A well-designed resource API usually maps these operations to standard HTTP methods.

7. HTTP Status Codes and API Responses

HTTP status codes communicate the outcome of a request. Returning the correct status makes it easier for clients to handle success, validation errors, authentication failures, and server problems.

Choose one consistent error-handling policy. Do not return 200 OK for every outcome if the request actually failed. Avoid exposing stack traces, SQL statements, passwords, or internal implementation details in client-facing error messages.

8. Designing Request and Response Bodies

REST APIs commonly exchange JSON. Request and response structures should be predictable, clearly named, and appropriate to the resource.

8.1 Example JSON Request

{
  "name": "Mechanical Keyboard",
  "price": 2499.00,
  "category": "Accessories",
  "inStock": true
}

8.2 Example JSON Response

{
  "id": 101,
  "name": "Mechanical Keyboard",
  "price": 2499.00,
  "category": "Accessories",
  "inStock": true
}

8.3 Use Consistent Field Names

Choose a naming convention, such as camelCase, and apply it consistently to JSON fields. Use meaningful names such as createdAt, customerId, and totalAmount.

8.4 Separate Input DTOs from Database Entities

A Data Transfer Object (DTO) defines the fields accepted or returned by an API. It helps prevent clients from directly controlling internal entity fields, such as administrative flags, audit columns, or password hashes.

public record ProductRequest(
    String name,
    java.math.BigDecimal price,
    String category
) {}

For projects using Java versions that do not support records, an ordinary class with fields, constructors, and accessors can be used instead.

9. Building RESTful Endpoints with Spring Boot

Spring Boot provides annotations for mapping HTTP requests to Java methods. The following example demonstrates a small in-memory product API for learning purposes. A production application should normally use a service layer, persistent repository, and appropriate exception handling.

9.1 Create a Spring Boot Project

Create a project using Spring Initializr and include Spring Web. Add Spring Validation if you want to use Bean Validation annotations such as @NotBlank and @Positive.

Official Spring guide: Building a RESTful Web Service with Spring.

9.2 Create a Product Model

package com.example.demo;

import java.math.BigDecimal;

public record Product(
    Long id,
    String name,
    BigDecimal price,
    String category
) {}

9.3 Create a REST Controller

package com.example.demo;

import java.math.BigDecimal;
import java.net.URI;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final Map<Long, Product> products =
        new ConcurrentHashMap<>();

    private final AtomicLong ids = new AtomicLong();

    @GetMapping
    public List<Product> getAllProducts() {
        return products.values().stream()
            .sorted(java.util.Comparator.comparing(Product::id))
            .toList();
    }

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(
            @PathVariable Long id) {
        Product product = products.get(id);
        return product == null
            ? ResponseEntity.notFound().build()
            : ResponseEntity.ok(product);
    }

    @PostMapping
    public ResponseEntity<Product> createProduct(
            @RequestBody ProductRequest request) {

        long id = ids.incrementAndGet();
        Product product = new Product(
            id,
            request.name(),
            request.price(),
            request.category()
        );

        products.put(id, product);

        return ResponseEntity
            .created(URI.create("/api/products/" + id))
            .body(product);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Product> replaceProduct(
            @PathVariable Long id,
            @RequestBody ProductRequest request) {

        if (!products.containsKey(id)) {
            return ResponseEntity.notFound().build();
        }

        Product updated = new Product(
            id,
            request.name(),
            request.price(),
            request.category()
        );

        products.put(id, updated);
        return ResponseEntity.ok(updated);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(
            @PathVariable Long id) {

        Product removed = products.remove(id);

        return removed == null
            ? ResponseEntity.notFound().build()
            : ResponseEntity.noContent().build();
    }

    public record ProductRequest(
        String name,
        BigDecimal price,
        String category
    ) {}
}

Important: This is a simplified teaching example. It does not include validation, database persistence, authorization, or robust concurrent update handling. Its data is lost when the application restarts. Add these capabilities before using a similar design in production.

9.4 Understanding the Annotations

10. Path Variables, Query Parameters, and Request Bodies

10.1 Path Variables

Use path variables to identify a specific resource.

@GetMapping("/api/orders/{orderId}")
public String getOrder(@PathVariable Long orderId) {
    return "Requested order: " + orderId;
}

Example request: GET /api/orders/500.

10.2 Query Parameters

Use query parameters to filter, sort, search, or paginate a collection.

@GetMapping("/api/products/search")
public String searchProducts(
        @RequestParam String keyword,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {

    return "Search: " + keyword
        + ", page: " + page
        + ", size: " + size;
}

Example request: GET /api/products/search?keyword=keyboard&page=0&size=20.

In a production API, validate pagination values, enforce a maximum page size, and apply the parameters to the database query rather than simply returning them.

10.3 Request Bodies

Use a request body for structured data submitted to create or update a resource. Specify the content type, usually application/json, and validate incoming fields before processing them.

11. Input Validation and Error Handling

Validation protects data quality and makes API behavior predictable. Validate required fields, formats, ranges, lengths, and business rules on the server, even if the frontend also validates input.

11.1 Add Validation Constraints

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
import java.math.BigDecimal;

public record ProductRequest(
    @NotBlank(message = "Product name is required")
    String name,

    @NotNull(message = "Price is required")
    @Positive(message = "Price must be greater than zero")
    BigDecimal price,

    @NotBlank(message = "Category is required")
    String category
) {}

Use @Valid on the controller request body and include the Spring Boot validation dependency.

@PostMapping
public ResponseEntity<Product> createProduct(
        @Valid @RequestBody ProductRequest request) {
    // Call the service to create the product.
    return ResponseEntity.accepted().build();
}

The example above illustrates validation activation, not a complete create operation. Replace the placeholder response with the actual created resource and an appropriate status code.

11.2 Centralize Exception Handling

Spring MVC supports @RestControllerAdvice for consistent error responses across controllers.

import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<Map<String, String>>
            handleIllegalArgument(IllegalArgumentException ex) {

        Map<String, String> error = Map.of(
            "error", "BAD_REQUEST",
            "message", ex.getMessage()
        );

        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body(error);
    }
}

In production, use specific application exceptions and avoid returning raw exception messages if they could reveal sensitive implementation details. For broader API error conventions, consider a consistent structure based on the Problem Details format supported by modern Spring applications.

12. Filtering, Sorting, Searching, and Pagination

Collection endpoints should remain efficient when datasets grow. Query parameters are commonly used to control the subset and order of returned records.

12.1 Filtering

GET /api/products?category=Accessories
GET /api/orders?status=SHIPPED

12.2 Sorting

GET /api/products?sort=price,asc
GET /api/employees?sort=lastName,desc

Validate requested sort fields against an allowlist. Do not directly concatenate arbitrary client-provided sort expressions into SQL.

12.3 Pagination

GET /api/products?page=0&size=20

Pagination limits response size and reduces unnecessary data transfer. A response may include metadata such as the current page, page size, total elements, and total pages.

{
  "items": [
    {
      "id": 101,
      "name": "Mechanical Keyboard",
      "price": 2499.00
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 125,
  "totalPages": 7
}

The sample response is illustrative. Select an appropriate pagination strategy for the use case. Offset pagination is simple, while cursor-based pagination can be more efficient and stable for large or frequently changing datasets.

13. API Versioning

Versioning helps evolve an API while giving existing clients time to adapt. A versioning strategy should be selected deliberately and documented.

13.1 URI Versioning

GET /api/v1/products
GET /api/v2/products

This approach is straightforward to understand and commonly used.

13.2 Header or Media-Type Versioning

An API can also use request headers or media types to distinguish versions. These approaches can keep version identifiers out of the URL, but they require clear documentation and careful client support.

13.3 Versioning Best Practices

• Do not introduce a new version for every small, backward-compatible change.
• Document breaking changes and migration steps.
• Define deprecation and support timelines.
• Keep behavior consistent within each version.
• Test older supported versions before deploying changes.

14. Security Considerations for REST Endpoints

API security should be considered during endpoint design, not added as an afterthought.

• Authentication: Verify the identity of the caller using an appropriate mechanism.
• Authorization: Check whether the caller is permitted to access the requested resource or perform the requested action.
• HTTPS: Protect traffic in transit.
• Input validation: Reject invalid data and enforce business rules on the server.
• Mass-assignment protection: Bind client input to dedicated DTOs rather than exposing every internal entity field.
• Rate limiting: Restrict excessive requests where appropriate.
• Sensitive data: Never expose passwords, secret keys, or private fields in responses or logs.
• Object-level authorization: Verify access to each requested record, not just the endpoint generally.
• CORS: Configure allowed browser origins, methods, and headers based on the application's needs.
• Audit logging: Record important security events without logging credentials or sensitive payloads.

Hiding an endpoint or using an unpredictable resource ID is not a replacement for authorization. A caller must not gain access to another user's resource simply by changing an ID in the URL.

15. Idempotency and Reliable API Design

An operation is idempotent when making the same request multiple times has the same intended effect as making it once. Idempotency is important when clients retry requests after timeouts or network failures.

For payment or order-creation APIs, an idempotency key can help prevent duplicate processing when a client retries a request. The server must store and enforce the key's result according to a documented policy.

16. API Documentation with OpenAPI

API documentation describes available endpoints, methods, parameters, request bodies, response formats, status codes, and authentication requirements. OpenAPI is a widely used specification for documenting HTTP APIs.

Useful documentation should include:

• Endpoint path and HTTP method.
• Purpose and expected behavior.
• Required path variables and query parameters.
• Example request bodies and responses.
• Possible success and error status codes.
• Authentication and authorization requirements.
• Pagination, filtering, sorting, and versioning rules.
• Deprecation notes and compatibility details.

For Spring Boot projects, teams commonly use Springdoc OpenAPI to generate interactive API documentation. Ensure the documentation reflects the actual implementation and does not expose sensitive internal endpoints.

17. Testing RESTful API Endpoints

Testing verifies that endpoints behave correctly for valid requests, invalid inputs, missing resources, and unauthorized access.

17.1 Testing with Postman or curl

Example request to retrieve products:

curl -i http://localhost:8080/api/products

Example request to create a product:

curl -i -X POST http://localhost:8080/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Mouse",
    "price": 799.00,
    "category": "Accessories"
  }'

Example request to retrieve one product:

curl -i http://localhost:8080/api/products/1

Example request to delete a product:

curl -i -X DELETE http://localhost:8080/api/products/1

17.2 Test Cases to Include

• Valid request returns the expected response and status code.
• Missing resource returns the documented not-found response.
• Invalid JSON returns a client error.
• Invalid field values are rejected.
• Missing or invalid authentication is handled correctly.
• Users cannot access resources they do not own or have permission to view.
• Pagination and filtering return the correct subset of data.
• Duplicate requests do not cause unintended side effects.
• Unexpected server errors do not expose sensitive implementation details.

17.3 Automated Tests

Spring Boot supports controller and integration testing. Depending on the test scope, use tools such as MockMvc, @WebMvcTest, and @SpringBootTest to verify routing, validation, serialization, status codes, and application behavior.

18. Common API Design Mistakes

19. Practical Exercise: Design an Employee Management API

Objective: Design a REST API for creating, retrieving, updating, and deleting employee records.

Requirements

• Create an employee with a name, email, department, and salary.
• Retrieve a paginated list of employees.
• Retrieve a specific employee by ID.
• Filter employees by department.
• Update an employee's details.
• Delete an employee record.
• Validate required fields and salary values.
• Return appropriate status codes and consistent error responses.
• Protect employee records with authentication and authorization.

Suggested Endpoint Contract

Suggested Project Structure

src/main/java/com/example/employee/
├── controller/
│   └── EmployeeController.java
├── service/
│   └── EmployeeService.java
├── repository/
│   └── EmployeeRepository.java
├── entity/
│   └── Employee.java
├── dto/
│   ├── EmployeeRequest.java
│   └── EmployeeResponse.java
├── exception/
│   └── GlobalExceptionHandler.java
└── EmployeeApplication.java

Use the controller for HTTP request mapping, the service for business logic, and the repository for persistence. Keep validation and authorization responsibilities clear, and write tests for successful and unsuccessful requests.

20. Best Practices for Designing RESTful Endpoints

• Use resource-oriented paths and consistent naming.
• Choose HTTP methods according to their intended semantics.
• Return accurate status codes and meaningful response headers.
• Define predictable JSON request, response, and error formats.
• Use DTOs to control what clients can submit and receive.
• Validate all client input on the server.
• Support pagination for large collections.
• Use filters and sorting parameters with clear documented behavior.
• Apply authentication and resource-level authorization.
• Design retry behavior carefully for operations with side effects.
• Document the API using OpenAPI or an equivalent specification.
• Automate unit, integration, and security tests.
• Monitor response times, failure rates, and unusual traffic patterns.
• Plan backward compatibility and deprecation before making breaking changes.

21. Interview Questions and Answers

Q1. What is a RESTful API endpoint?

Answer: It is an address through which a client accesses or operates on a resource using HTTP. The endpoint path identifies the target, and the HTTP method communicates the intended operation.

Q2. What is the difference between REST and RESTful?

Answer: REST refers to an architectural style and its constraints. RESTful describes a system or API that follows those principles to an appropriate degree.

Q3. Why should endpoint URLs generally use nouns?

Answer: Nouns identify resources, while HTTP methods express standard actions. This approach makes paths consistent and easier to understand.

Q4. What is the difference between PUT and PATCH?

Answer: PUT normally replaces a resource representation, while PATCH applies a partial modification according to a defined patch format.

Q5. What is the difference between 401 and 403?

Answer: A 401 response indicates that valid authentication credentials are missing or not accepted. A 403 response indicates that access is forbidden, typically because the caller lacks permission.

Q6. When should an API return 201 Created?

Answer: When a request successfully creates a resource. A Location header can identify the newly created resource.

Q7. Why is pagination important?

Answer: Pagination limits the amount of data returned in a single response, improving response time, resource usage, and client usability.

Q8. What is idempotency?

Answer: It means repeating an operation has the same intended effect as performing it once. It is important when requests may be retried after network failures.

Q9. What is the role of DTOs in REST API development?

Answer: DTOs define the data accepted or returned by an endpoint. They separate the API contract from internal database entities and help control exposed fields.

Q10. How does Spring Boot create REST endpoints?

Answer: Spring Boot uses controller classes, commonly annotated with @RestController, and mapping annotations such as @GetMapping and @PostMapping to connect HTTP requests to Java methods.

Q11. How should API errors be handled?

Answer: Use suitable HTTP status codes, a consistent error format, validation, and centralized exception handling. Avoid returning internal stack traces or sensitive information.

Q12. How can REST APIs be secured?

Answer: Use HTTPS, authentication, authorization, input validation, rate limiting where appropriate, safe error handling, and resource-level permission checks.

22. Quick Revision Checklist

• Identify the resources the application manages.
• Choose consistent, resource-oriented URL paths.
• Map CRUD operations to appropriate HTTP methods.
• Use path variables for resource identifiers.
• Use query parameters for filtering, sorting, and pagination.
• Define clear JSON request and response formats.
• Return suitable HTTP status codes.
• Validate input and centralize error handling.
• Apply authentication and authorization checks.
• Document and test every endpoint.
• Consider idempotency, versioning, monitoring, and compatibility.

23. Conclusion

Designing RESTful API endpoints involves more than choosing URL paths. A robust API combines resource-oriented naming, correct HTTP method semantics, consistent status codes, well-defined request and response formats, validation, security, documentation, and testing.

Spring Boot makes these practices practical through its REST controller annotations and HTTP response support. By applying the concepts in these notes and completing the employee management exercise, learners can build APIs that are easier to integrate, maintain, test, and scale.

Continue learning: Explore the Advanced Java Training course, register for a course demo, or visit the JustAcademy website.

Additional Learning Resources

• Spring: Building a RESTful Web Service
• MDN: HTTP Request Methods
• API Design Best Practices